%=======================================================================
% CVS: $Id: ice_integrate.tex 5 2005-12-12 17:41:05Z mvr $
% CVS: $Source$
% CVS: $Name$
%=======================================================================

\section{Software Integration Procedure}

This section outlines the steps for testing and integrating newly developed
code into the existing sea ice model.  This procedure has been designed to
ensure that new code meets CCSM and CSIM requirements and improves the climate
simulation and/or the model performance.  All substantial code changes
must go through the Polar Climate Working Group ({\bf \textsl{PCWG}}) review process.
Substantial refers to all physics changes and any software engineering
changes that result in major changes to code organization and/or efficiency.
This generally does not include cosmetic changes to the code.

It may not be possible or necessary for a developer to carry out all of the steps
described in this section. For most development, it will be necessary to 
contact the liaison or a co-chair of the Polar Climate Working Group. This
information is on the PCWG web page: \\

\begin{htmlonly}
\htmladdnormallink{\tt http://www.ccsm.ucar.edu/working_groups/Polar/}
                      {http://www.ccsm.ucar.edu/working_groups/Polar/}. \\
\end{htmlonly}
\begin{latexonly}
  {\tt http://www.ccsm.ucar.edu/working\_groups/Polar/}. \\
\end{latexonly}

The PCWG review process will usually involve the following steps:

\begin{enumerate}
  \item Modeler develops improved code.  This can include modification
        of a few lines, improving a parameterization, or providing a
        new physics module.
  \item Modeler tests changes within CCSM framework.  See sections 
        \ref{control_run} and \ref{testing_mods}.
  \item Outcome of tests is posted on PCWG web site and modeler provides
        explanation to PCWG members.
  \item PCWG members review results (and code if desired).
  \item PCWG decide whether to recommend adoption of change to CCSM Code
        Review Board.
\end{enumerate}

\subsection{Making a Control Run}
\label{control_run}

Before new code is put into CSIM, a control run using the latest tagged
version of CCSM may need to be done to document the effects of the new
code on model performance and the simulated climate.  If newly
developed code is being put into a tagged version of CCSM, output from a
standard control run may already be available, in which case, this
set of steps can be skipped.  If output from a control run is not available,
here are the steps to create it:

\begin{enumerate}

  \item  Get a tagged version of CCSM via one of the following options:
    \begin{enumerate}
      \item  At {\bf \textsl{NCAR}}:
        \begin{enumerate}
          \item Check it out from CVS: {\tt cvs co -r ccsm\_tag\_name} 
          \item Copy it from {\tt /fs/cgd/csm/collections}
        \end{enumerate}
      \item  Off site:
        \begin{enumerate}
          \item Download it from http://www.ccsm.ucar.edu/models/ccsm3
          \item Contact the PCWG liaison or a co-chair for a copy.
        \end{enumerate}
    \end{enumerate}
  If you have questions regarding the appropriate CCSM tag name to use,
  contact a PCWG co-chair or the liaison.

  \item  See the CCSM User's Guide on how to set up the scripts for the 
         {\bf \textsl{M component set}} (latm, dlnd, docn, csim (mixed layer
         ocean mode), cpl).

  \item  Modify the latm source code and setup script to use your favorite
         forcing.  The PCWG can provide reasonable input datasets if needed.

  \item  Do a 10-15 year simulation to get a control run case, saving output
         in a permanent disk location.

  \item  Document performance by saving the timing information at the bottom of
         a log file, and put plots of output on web if necessary.  A graphics
         package is available for plotting output.

\end{enumerate}

\subsection{Testing Climate and Performance of Modified Code}
\label{testing_mods}

For purposes of adding new code to the existing model, a tagged version
of CCSM should be used, the more recent the better.  The latest version 
of CCSM will usually contain the latest version of CSIM. It is
a good idea to check if this is the case.  These are the steps for
integrating newly developed code into the existing sea ice model and testing:

\begin{enumerate}

  \item  Make modifications to the source code using one of the following options:
    \begin{enumerate}
      \item  Using CVS:
        \begin{enumerate}
          \item  Create a development branch from a CSIM tag on the main trunk, ideally
                 the CSIM tag used in the control run.
        \end{enumerate}
      \item  Not using CVS:
        \begin{enumerate}
          \item Copy modules to be modified from the source code directory to \\
                {\tt ccsm3/scripts/\$CASE/SourceMods/src.csim}, and make modifications
                in this directory.
        \end{enumerate}
    \end{enumerate}

  \item  Compile, run for 5 days with minimum debugging turned on: array
         bounds check, Nan initialization, floating point trap.

  \item  Check that code still meets any requirements that may have been
         affected by the new code.  The minimum tests are exact restart
         and conservation.  If developed code involves any namelist variables,
         all options for those variables must be tested.  Any tests
         available in the new code should be exercised.

  \item  Test on all supported platforms.  Compilation and a 5 day run are the
         minimum.

  \item  Do a 1 year run, check results against control run.

  \item  Continue run out to 10-15 years, saving output in a permanent disk location.
         This may be used as the next control run.

  \item  Document performance, compare with control run and put difference plots on web.

  \item  If results are satisfactory (approved by PCWG), code may be inspected
         and/or reviewed. Development branch will be merged with the main trunk
         and tagged.

  \item  Model documentation (User's Guide, Code Reference and Scientific Description)
         must be updated.

\end{enumerate}

Currently, there is no formal CCSM Requirements document, and the CSIM Requirements
document is still in the draft stage.  There is a somewhat complete list
of tests for CSIM, but an automated test suite is still under development.
All developers are strongly encouraged to read the CSIM Requirements Document
and all of the Developer's Guide (this document).

\subsubsection*{Minimum Requirements}

It is difficult to define all tests that are suitable for all code changes,
and a user may not have access to all supported platforms.  This section gives
a list of basic requirements for the ice model, to provide guidance for testing.
A more complete list of requirements is in the CSIM Requirements document
(under development).  As noted in section \ref{testing_mods},
any changes in climate or model performance due to the code modifications
must be documented.

\begin{description}

  \item [Minimum CCSM Requirements] Compiles, runs, and restarts exactly with
                        at least one configuration, preferably the 
                        {\bf \textsl{M component set}} (latm, dlnd, docn, csim in mixed
                        layer ocean mode, cpl) or the
                        {\bf \textsl{B component set}} (cam, clm, pop, csim, cpl).
              Runs on at least one standard CCSM grid (gx1v3 or gx3v5).
             Runs on all CCSM supported platforms available to the modeler.

  \item [Conservation] checking water, salt and energy budgets in the log file.
        Any conservation errors or CFL violations that occurred in the 10-15 year
        climate year run should be documented.

  \item [Exact Restart] This test is automated in the CSIM and CCSM scripts.
                       It does a 10 day startup run and a 5 day continuation
                       run that begins at day 5 of the startup run. Output from
                       days 5-10 of both runs are compared and must match bit-for-bit.

  \item [Debug Test] This test is also automated in the CSIM and CCSM scripts.

  \item[Input Data Files] If any new or modified input data files are necessary to
                          run the modified code, they must be provided with the code.
\end{description}
